
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  
<!-- Mirrored from werkzeug.palletsprojects.com/en/1.0.x/exceptions/ by HTTrack Website Copier/3.x [XR&CO'2014], Tue, 15 Sep 2020 06:37:09 GMT -->
<head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>HTTP Exceptions &#8212; Werkzeug Documentation (1.0.x)</title>
    <link rel="stylesheet" href="../_static/werkzeug.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" type="text/css" href="../../../../assets.readthedocs.org/static/css/badge_only.css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script async="async" type="text/javascript" src="../../../../assets.readthedocs.org/static/javascript/readthedocs-doc-embed.js"></script>
    <link rel="shortcut icon" href="../_static/favicon.ico"/>
    <link rel="index" title="Index" href="../genindex/index.html" />
    <link rel="search" title="Search" href="../search/index.html" />
    <link rel="next" title="Application Deployment" href="../deployment/index.html" />
    <link rel="prev" title="Application Profiler" href="../middleware/profiler/index.html" />
    <link rel="canonical" href="index.html">
  <script>DOCUMENTATION_OPTIONS.URL_ROOT = '../index.html';</script>
   
  
<!-- RTD Extra Head -->

<!-- 
Always link to the latest version, as canonical.
http://docs.readthedocs.org/en/latest/canonical.html
-->
<link rel="canonical" href="index.html" />

<link rel="stylesheet" href="../../../../assets.readthedocs.org/static/css/readthedocs-doc-embed.css" type="text/css" />

<script type="text/javascript" src="../_static/readthedocs-data.js"></script>

<!-- Add page-specific data, which must exist in the page js, not global -->
<script type="text/javascript">
READTHEDOCS_DATA['page'] = "exceptions"
READTHEDOCS_DATA['source_suffix'] = ".rst"
</script>

<script type="text/javascript" src="../../../../assets.readthedocs.org/static/javascript/readthedocs-analytics.js" async="async"></script>

<!-- end RTD <extrahead> -->
</head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex/index.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../py-modindex/index.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="../deployment/index.html" title="Application Deployment"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="../middleware/profiler/index.html" title="Application Profiler"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">Werkzeug Documentation (1.0.x)</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="module-werkzeug.exceptions">
<span id="http-exceptions"></span><h1>HTTP Exceptions<a class="headerlink" href="#module-werkzeug.exceptions" title="Permalink to this headline">¶</a></h1>
<div class="section" id="werkzeug-exceptions">
<h2>werkzeug.exceptions<a class="headerlink" href="#werkzeug-exceptions" title="Permalink to this headline">¶</a></h2>
<p>This module implements a number of Python exceptions you can raise from
within your views to trigger a standard non-200 response.</p>
<div class="section" id="usage-example">
<h3>Usage Example<a class="headerlink" href="#usage-example" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">werkzeug.wrappers</span> <span class="k">import</span> <span class="n">BaseRequest</span>
<span class="kn">from</span> <span class="nn">werkzeug.wsgi</span> <span class="k">import</span> <span class="n">responder</span>
<span class="kn">from</span> <span class="nn">werkzeug.exceptions</span> <span class="k">import</span> <span class="n">HTTPException</span><span class="p">,</span> <span class="n">NotFound</span>

<span class="k">def</span> <span class="nf">view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="k">raise</span> <span class="n">NotFound</span><span class="p">()</span>

<span class="nd">@responder</span>
<span class="k">def</span> <span class="nf">application</span><span class="p">(</span><span class="n">environ</span><span class="p">,</span> <span class="n">start_response</span><span class="p">):</span>
    <span class="n">request</span> <span class="o">=</span> <span class="n">BaseRequest</span><span class="p">(</span><span class="n">environ</span><span class="p">)</span>
    <span class="k">try</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">view</span><span class="p">(</span><span class="n">request</span><span class="p">)</span>
    <span class="k">except</span> <span class="n">HTTPException</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">e</span>
</pre></div>
</div>
<p>As you can see from this example those exceptions are callable WSGI
applications.  Because of Python 2.4 compatibility those do not extend
from the response objects but only from the python exception class.</p>
<p>As a matter of fact they are not Werkzeug response objects.  However you
can get a response object by calling <code class="docutils literal notranslate"><span class="pre">get_response()</span></code> on a HTTP
exception.</p>
<p>Keep in mind that you have to pass an environment to <code class="docutils literal notranslate"><span class="pre">get_response()</span></code>
because some errors fetch additional information from the WSGI
environment.</p>
<p>If you want to hook in a different exception page to say, a 404 status
code, you can add a second except for a specific subclass of an error:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@responder</span>
<span class="k">def</span> <span class="nf">application</span><span class="p">(</span><span class="n">environ</span><span class="p">,</span> <span class="n">start_response</span><span class="p">):</span>
    <span class="n">request</span> <span class="o">=</span> <span class="n">BaseRequest</span><span class="p">(</span><span class="n">environ</span><span class="p">)</span>
    <span class="k">try</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">view</span><span class="p">(</span><span class="n">request</span><span class="p">)</span>
    <span class="k">except</span> <span class="n">NotFound</span><span class="p">,</span> <span class="n">e</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">not_found</span><span class="p">(</span><span class="n">request</span><span class="p">)</span>
    <span class="k">except</span> <span class="n">HTTPException</span><span class="p">,</span> <span class="n">e</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">e</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="error-classes">
<h2>Error Classes<a class="headerlink" href="#error-classes" title="Permalink to this headline">¶</a></h2>
<p>The following error classes exist in Werkzeug:</p>
<dl class="exception">
<dt id="werkzeug.exceptions.BadRequest">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">BadRequest</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.BadRequest" title="Permalink to this definition">¶</a></dt>
<dd><p><em>400</em> <cite>Bad Request</cite></p>
<p>Raise if the browser sends something to the application the application
or server cannot handle.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.Unauthorized">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">Unauthorized</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em>, <em>www_authenticate=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.Unauthorized" title="Permalink to this definition">¶</a></dt>
<dd><p><em>401</em> <code class="docutils literal notranslate"><span class="pre">Unauthorized</span></code></p>
<p>Raise if the user is not authorized to access a resource.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">www_authenticate</span></code> argument should be used to set the
<code class="docutils literal notranslate"><span class="pre">WWW-Authenticate</span></code> header. This is used for HTTP basic auth and
other schemes. Use <a class="reference internal" href="../datastructures/index.html#werkzeug.datastructures.WWWAuthenticate" title="werkzeug.datastructures.WWWAuthenticate"><code class="xref py py-class docutils literal notranslate"><span class="pre">WWWAuthenticate</span></code></a>
to create correctly formatted values. Strictly speaking a 401
response is invalid if it doesn’t provide at least one value for
this header, although real clients typically don’t care.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>description</strong> – Override the default message used for the body
of the response.</li>
<li><strong>www-authenticate</strong> – A single value, or list of values, for the
WWW-Authenticate header.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<details class="changelog">
<summary>Changelog</summary><div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.15.3: </span>If the <code class="docutils literal notranslate"><span class="pre">www_authenticate</span></code> argument is not set, the
<code class="docutils literal notranslate"><span class="pre">WWW-Authenticate</span></code> header is not set.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.15.3: </span>The <code class="docutils literal notranslate"><span class="pre">response</span></code> argument was restored.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.15.1: </span><code class="docutils literal notranslate"><span class="pre">description</span></code> was moved back as the first argument, restoring
 its previous position.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.15.0: </span><code class="docutils literal notranslate"><span class="pre">www_authenticate</span></code> was added as the first argument, ahead of
<code class="docutils literal notranslate"><span class="pre">description</span></code>.</p>
</div>
</details></dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.Forbidden">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">Forbidden</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.Forbidden" title="Permalink to this definition">¶</a></dt>
<dd><p><em>403</em> <cite>Forbidden</cite></p>
<p>Raise if the user doesn’t have the permission for the requested resource
but was authenticated.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.NotFound">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">NotFound</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.NotFound" title="Permalink to this definition">¶</a></dt>
<dd><p><em>404</em> <cite>Not Found</cite></p>
<p>Raise if a resource does not exist and never existed.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.MethodNotAllowed">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">MethodNotAllowed</code><span class="sig-paren">(</span><em>valid_methods=None</em>, <em>description=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.MethodNotAllowed" title="Permalink to this definition">¶</a></dt>
<dd><p><em>405</em> <cite>Method Not Allowed</cite></p>
<p>Raise if the server used a method the resource does not handle.  For
example <cite>POST</cite> if the resource is view only.  Especially useful for REST.</p>
<p>The first argument for this exception should be a list of allowed methods.
Strictly speaking the response would be invalid if you don’t provide valid
methods in the header which you can do with that list.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.NotAcceptable">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">NotAcceptable</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.NotAcceptable" title="Permalink to this definition">¶</a></dt>
<dd><p><em>406</em> <cite>Not Acceptable</cite></p>
<p>Raise if the server can’t return any content conforming to the
<cite>Accept</cite> headers of the client.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.RequestTimeout">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">RequestTimeout</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.RequestTimeout" title="Permalink to this definition">¶</a></dt>
<dd><p><em>408</em> <cite>Request Timeout</cite></p>
<p>Raise to signalize a timeout.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.Conflict">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">Conflict</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.Conflict" title="Permalink to this definition">¶</a></dt>
<dd><p><em>409</em> <cite>Conflict</cite></p>
<p>Raise to signal that a request cannot be completed because it conflicts
with the current state on the server.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.7.</span></p>
</div>
</details></dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.Gone">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">Gone</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.Gone" title="Permalink to this definition">¶</a></dt>
<dd><p><em>410</em> <cite>Gone</cite></p>
<p>Raise if a resource existed previously and went away without new location.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.LengthRequired">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">LengthRequired</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.LengthRequired" title="Permalink to this definition">¶</a></dt>
<dd><p><em>411</em> <cite>Length Required</cite></p>
<p>Raise if the browser submitted data but no <code class="docutils literal notranslate"><span class="pre">Content-Length</span></code> header which
is required for the kind of processing the server does.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.PreconditionFailed">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">PreconditionFailed</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.PreconditionFailed" title="Permalink to this definition">¶</a></dt>
<dd><p><em>412</em> <cite>Precondition Failed</cite></p>
<p>Status code used in combination with <code class="docutils literal notranslate"><span class="pre">If-Match</span></code>, <code class="docutils literal notranslate"><span class="pre">If-None-Match</span></code>, or
<code class="docutils literal notranslate"><span class="pre">If-Unmodified-Since</span></code>.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.RequestEntityTooLarge">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">RequestEntityTooLarge</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.RequestEntityTooLarge" title="Permalink to this definition">¶</a></dt>
<dd><p><em>413</em> <cite>Request Entity Too Large</cite></p>
<p>The status code one should return if the data submitted exceeded a given
limit.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.RequestURITooLarge">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">RequestURITooLarge</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.RequestURITooLarge" title="Permalink to this definition">¶</a></dt>
<dd><p><em>414</em> <cite>Request URI Too Large</cite></p>
<p>Like <em>413</em> but for too long URLs.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.UnsupportedMediaType">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">UnsupportedMediaType</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.UnsupportedMediaType" title="Permalink to this definition">¶</a></dt>
<dd><p><em>415</em> <cite>Unsupported Media Type</cite></p>
<p>The status code returned if the server is unable to handle the media type
the client transmitted.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.RequestedRangeNotSatisfiable">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">RequestedRangeNotSatisfiable</code><span class="sig-paren">(</span><em>length=None</em>, <em>units='bytes'</em>, <em>description=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.RequestedRangeNotSatisfiable" title="Permalink to this definition">¶</a></dt>
<dd><p><em>416</em> <cite>Requested Range Not Satisfiable</cite></p>
<p>The client asked for an invalid part of the file.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.7.</span></p>
</div>
</details></dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.ExpectationFailed">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">ExpectationFailed</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.ExpectationFailed" title="Permalink to this definition">¶</a></dt>
<dd><p><em>417</em> <cite>Expectation Failed</cite></p>
<p>The server cannot meet the requirements of the Expect request-header.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.7.</span></p>
</div>
</details></dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.ImATeapot">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">ImATeapot</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.ImATeapot" title="Permalink to this definition">¶</a></dt>
<dd><p><em>418</em> <cite>I’m a teapot</cite></p>
<p>The server should return this if it is a teapot and someone attempted
to brew coffee with it.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.7.</span></p>
</div>
</details></dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.UnprocessableEntity">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">UnprocessableEntity</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.UnprocessableEntity" title="Permalink to this definition">¶</a></dt>
<dd><p><em>422</em> <cite>Unprocessable Entity</cite></p>
<p>Used if the request is well formed, but the instructions are otherwise
incorrect.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.Locked">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">Locked</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.Locked" title="Permalink to this definition">¶</a></dt>
<dd><p><em>423</em> <cite>Locked</cite></p>
<p>Used if the resource that is being accessed is locked.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.FailedDependency">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">FailedDependency</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.FailedDependency" title="Permalink to this definition">¶</a></dt>
<dd><p><em>424</em> <cite>Failed Dependency</cite></p>
<p>Used if the method could not be performed on the resource
because the requested action depended on another action and that action failed.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.PreconditionRequired">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">PreconditionRequired</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.PreconditionRequired" title="Permalink to this definition">¶</a></dt>
<dd><p><em>428</em> <cite>Precondition Required</cite></p>
<p>The server requires this request to be conditional, typically to prevent
the lost update problem, which is a race condition between two or more
clients attempting to update a resource through PUT or DELETE. By requiring
each client to include a conditional header (“If-Match” or “If-Unmodified-
Since”) with the proper value retained from a recent GET request, the
server ensures that each client has at least seen the previous revision of
the resource.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.TooManyRequests">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">TooManyRequests</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em>, <em>retry_after=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.TooManyRequests" title="Permalink to this definition">¶</a></dt>
<dd><p><em>429</em> <cite>Too Many Requests</cite></p>
<p>The server is limiting the rate at which this user receives
responses, and this request exceeds that rate. (The server may use
any convenient method to identify users and their request rates).
The server may include a “Retry-After” header to indicate how long
the user should wait before retrying.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>retry_after</strong> – If given, set the <code class="docutils literal notranslate"><span class="pre">Retry-After</span></code> header to this
value. May be an <a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.8)"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> number of seconds or a
<a class="reference external" href="https://docs.python.org/3/library/datetime.html#datetime.datetime" title="(in Python v3.8)"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a>.</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.0: </span>Added <code class="docutils literal notranslate"><span class="pre">retry_after</span></code> parameter.</p>
</div>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.RequestHeaderFieldsTooLarge">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">RequestHeaderFieldsTooLarge</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.RequestHeaderFieldsTooLarge" title="Permalink to this definition">¶</a></dt>
<dd><p><em>431</em> <cite>Request Header Fields Too Large</cite></p>
<p>The server refuses to process the request because the header fields are too
large. One or more individual fields may be too large, or the set of all
headers is too large.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.UnavailableForLegalReasons">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">UnavailableForLegalReasons</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.UnavailableForLegalReasons" title="Permalink to this definition">¶</a></dt>
<dd><p><em>451</em> <cite>Unavailable For Legal Reasons</cite></p>
<p>This status code indicates that the server is denying access to the
resource as a consequence of a legal demand.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.InternalServerError">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">InternalServerError</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em>, <em>original_exception=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.InternalServerError" title="Permalink to this definition">¶</a></dt>
<dd><p><em>500</em> <cite>Internal Server Error</cite></p>
<p>Raise if an internal server error occurred.  This is a good fallback if an
unknown error occurred in the dispatcher.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.0.0: </span>Added the <a class="reference internal" href="#werkzeug.exceptions.InternalServerError.original_exception" title="werkzeug.exceptions.InternalServerError.original_exception"><code class="xref py py-attr docutils literal notranslate"><span class="pre">original_exception</span></code></a> attribute.</p>
</div>
<dl class="attribute">
<dt id="werkzeug.exceptions.InternalServerError.original_exception">
<code class="descname">original_exception</code><em class="property"> = None</em><a class="headerlink" href="#werkzeug.exceptions.InternalServerError.original_exception" title="Permalink to this definition">¶</a></dt>
<dd><p>The original exception that caused this 500 error. Can be
used by frameworks to provide context when handling
unexpected errors.</p>
</dd></dl>

</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.NotImplemented">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">NotImplemented</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.NotImplemented" title="Permalink to this definition">¶</a></dt>
<dd><p><em>501</em> <cite>Not Implemented</cite></p>
<p>Raise if the application does not support the action requested by the
browser.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.BadGateway">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">BadGateway</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.BadGateway" title="Permalink to this definition">¶</a></dt>
<dd><p><em>502</em> <cite>Bad Gateway</cite></p>
<p>If you do proxying in your application you should return this status code
if you received an invalid response from the upstream server it accessed
in attempting to fulfill the request.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.ServiceUnavailable">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">ServiceUnavailable</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em>, <em>retry_after=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.ServiceUnavailable" title="Permalink to this definition">¶</a></dt>
<dd><p><em>503</em> <cite>Service Unavailable</cite></p>
<p>Status code you should return if a service is temporarily
unavailable.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>retry_after</strong> – If given, set the <code class="docutils literal notranslate"><span class="pre">Retry-After</span></code> header to this
value. May be an <a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.8)"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> number of seconds or a
<a class="reference external" href="https://docs.python.org/3/library/datetime.html#datetime.datetime" title="(in Python v3.8)"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a>.</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.0: </span>Added <code class="docutils literal notranslate"><span class="pre">retry_after</span></code> parameter.</p>
</div>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.GatewayTimeout">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">GatewayTimeout</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.GatewayTimeout" title="Permalink to this definition">¶</a></dt>
<dd><p><em>504</em> <cite>Gateway Timeout</cite></p>
<p>Status code you should return if a connection to an upstream server
times out.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.HTTPVersionNotSupported">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">HTTPVersionNotSupported</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.HTTPVersionNotSupported" title="Permalink to this definition">¶</a></dt>
<dd><p><em>505</em> <cite>HTTP Version Not Supported</cite></p>
<p>The server does not support the HTTP protocol version used in the request.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.HTTPUnicodeError">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">HTTPUnicodeError</code><a class="headerlink" href="#werkzeug.exceptions.HTTPUnicodeError" title="Permalink to this definition">¶</a></dt>
<dd><p>This exception is used to signal unicode decode errors of request
data.  For more information see the <a class="reference internal" href="../unicode/index.html#unicode"><span class="std std-ref">Unicode</span></a> chapter.</p>
</dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.ClientDisconnected">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">ClientDisconnected</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.ClientDisconnected" title="Permalink to this definition">¶</a></dt>
<dd><p>Internal exception that is raised if Werkzeug detects a disconnected
client.  Since the client is already gone at that point attempting to
send the error message to the client might not work and might ultimately
result in another exception in the server.  Mainly this is here so that
it is silenced by default as far as Werkzeug is concerned.</p>
<p>Since disconnections cannot be reliably detected and are unspecified
by WSGI to a large extent this might or might not be raised if a client
is gone.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.8.</span></p>
</div>
</details></dd></dl>

<dl class="exception">
<dt id="werkzeug.exceptions.SecurityError">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">SecurityError</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.SecurityError" title="Permalink to this definition">¶</a></dt>
<dd><p>Raised if something triggers a security error.  This is otherwise
exactly like a bad request error.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.9.</span></p>
</div>
</details></dd></dl>

</div>
<div class="section" id="baseclass">
<h2>Baseclass<a class="headerlink" href="#baseclass" title="Permalink to this headline">¶</a></h2>
<p>All the exceptions implement this common interface:</p>
<dl class="exception">
<dt id="werkzeug.exceptions.HTTPException">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">HTTPException</code><span class="sig-paren">(</span><em>description=None</em>, <em>response=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.HTTPException" title="Permalink to this definition">¶</a></dt>
<dd><p>Baseclass for all HTTP exceptions.  This exception can be called as WSGI
application to render a default error page or you can catch the subclasses
of it independently and render nicer error messages.</p>
<dl class="method">
<dt id="werkzeug.exceptions.HTTPException.__call__">
<code class="descname">__call__</code><span class="sig-paren">(</span><em>environ</em>, <em>start_response</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.HTTPException.__call__" title="Permalink to this definition">¶</a></dt>
<dd><p>Call the exception as WSGI application.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>environ</strong> – the WSGI environment.</li>
<li><strong>start_response</strong> – the response callable provided by the WSGI
server.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="werkzeug.exceptions.HTTPException.get_response">
<code class="descname">get_response</code><span class="sig-paren">(</span><em>environ=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.HTTPException.get_response" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a response object.  If one was passed to the exception
it’s returned directly.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>environ</strong> – the optional environ for the request.  This
can be used to modify the response depending
on how the request looked like.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">a <code class="xref py py-class docutils literal notranslate"><span class="pre">Response</span></code> object or a subclass thereof.</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="special-http-exceptions">
<h2>Special HTTP Exceptions<a class="headerlink" href="#special-http-exceptions" title="Permalink to this headline">¶</a></h2>
<p>Starting with Werkzeug 0.3 some of the builtin classes raise exceptions that
look like regular python exceptions (eg <a class="reference external" href="https://docs.python.org/3/library/exceptions.html#KeyError" title="(in Python v3.8)"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a>) but are
<a class="reference internal" href="#werkzeug.exceptions.BadRequest" title="werkzeug.exceptions.BadRequest"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BadRequest</span></code></a> HTTP exceptions at the same time.  This decision was made
to simplify a common pattern where you want to abort if the client tampered
with the submitted form data in a way that the application can’t recover
properly and should abort with <code class="docutils literal notranslate"><span class="pre">400</span> <span class="pre">BAD</span> <span class="pre">REQUEST</span></code>.</p>
<p>Assuming the application catches all HTTP exceptions and reacts to them
properly a view function could do the following safely and doesn’t have to
check if the keys exist:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">new_post</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="n">post</span> <span class="o">=</span> <span class="n">Post</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="n">request</span><span class="o">.</span><span class="n">form</span><span class="p">[</span><span class="s1">&#39;title&#39;</span><span class="p">],</span> <span class="n">body</span><span class="o">=</span><span class="n">request</span><span class="o">.</span><span class="n">form</span><span class="p">[</span><span class="s1">&#39;body&#39;</span><span class="p">])</span>
    <span class="n">post</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
    <span class="k">return</span> <span class="n">redirect</span><span class="p">(</span><span class="n">post</span><span class="o">.</span><span class="n">url</span><span class="p">)</span>
</pre></div>
</div>
<p>If <cite>title</cite> or <cite>body</cite> are missing in the form, a special key error will be
raised which behaves like a <a class="reference external" href="https://docs.python.org/3/library/exceptions.html#KeyError" title="(in Python v3.8)"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> but also a <a class="reference internal" href="#werkzeug.exceptions.BadRequest" title="werkzeug.exceptions.BadRequest"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BadRequest</span></code></a>
exception.</p>
<dl class="exception">
<dt id="werkzeug.exceptions.BadRequestKeyError">
<em class="property">exception </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">BadRequestKeyError</code><span class="sig-paren">(</span><em>arg=None</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.BadRequestKeyError" title="Permalink to this definition">¶</a></dt>
<dd><p>An exception that is used to signal both a <a class="reference external" href="https://docs.python.org/3/library/exceptions.html#KeyError" title="(in Python v3.8)"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> and a
<a class="reference internal" href="#werkzeug.exceptions.BadRequest" title="werkzeug.exceptions.BadRequest"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BadRequest</span></code></a>. Used by many of the datastructures.</p>
</dd></dl>

</div>
<div class="section" id="simple-aborting">
<h2>Simple Aborting<a class="headerlink" href="#simple-aborting" title="Permalink to this headline">¶</a></h2>
<p>Sometimes it’s convenient to just raise an exception by the error code,
without importing the exception and looking up the name etc.  For this
purpose there is the <a class="reference internal" href="#werkzeug.exceptions.abort" title="werkzeug.exceptions.abort"><code class="xref py py-func docutils literal notranslate"><span class="pre">abort()</span></code></a> function.</p>
<dl class="function">
<dt id="werkzeug.exceptions.abort">
<code class="descclassname">werkzeug.exceptions.</code><code class="descname">abort</code><span class="sig-paren">(</span><em>status</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.abort" title="Permalink to this definition">¶</a></dt>
<dd><p>Raises an <a class="reference internal" href="#werkzeug.exceptions.HTTPException" title="werkzeug.exceptions.HTTPException"><code class="xref py py-exc docutils literal notranslate"><span class="pre">HTTPException</span></code></a> for the given status code or WSGI
application.</p>
<p>If a status code is given, it will be looked up in the list of
exceptions and will raise that exception.  If passed a WSGI application,
it will wrap it in a proxy WSGI exception and raise that:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">abort</span><span class="p">(</span><span class="mi">404</span><span class="p">)</span>  <span class="c1"># 404 Not Found</span>
<span class="n">abort</span><span class="p">(</span><span class="n">Response</span><span class="p">(</span><span class="s1">&#39;Hello World&#39;</span><span class="p">))</span>
</pre></div>
</div>
</dd></dl>

<p>If you want to use this functionality with custom exceptions you can
create an instance of the aborter class:</p>
<dl class="class">
<dt id="werkzeug.exceptions.Aborter">
<em class="property">class </em><code class="descclassname">werkzeug.exceptions.</code><code class="descname">Aborter</code><span class="sig-paren">(</span><em>mapping=None</em>, <em>extra=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.exceptions.Aborter" title="Permalink to this definition">¶</a></dt>
<dd><p>When passed a dict of code -&gt; exception items it can be used as
callable that raises exceptions.  If the first argument to the
callable is an integer it will be looked up in the mapping, if it’s
a WSGI application it will be raised in a proxy exception.</p>
<p>The rest of the arguments are forwarded to the exception constructor.</p>
</dd></dl>

</div>
<div class="section" id="custom-errors">
<h2>Custom Errors<a class="headerlink" href="#custom-errors" title="Permalink to this headline">¶</a></h2>
<p>As you can see from the list above not all status codes are available as
errors.  Especially redirects and other non 200 status codes that do not
represent errors are missing.  For redirects you can use the <code class="xref py py-func docutils literal notranslate"><span class="pre">redirect()</span></code>
function from the utilities.</p>
<p>If you want to add an error yourself you can subclass <a class="reference internal" href="#werkzeug.exceptions.HTTPException" title="werkzeug.exceptions.HTTPException"><code class="xref py py-exc docutils literal notranslate"><span class="pre">HTTPException</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">werkzeug.exceptions</span> <span class="k">import</span> <span class="n">HTTPException</span>

<span class="k">class</span> <span class="nc">PaymentRequired</span><span class="p">(</span><span class="n">HTTPException</span><span class="p">):</span>
    <span class="n">code</span> <span class="o">=</span> <span class="mi">402</span>
    <span class="n">description</span> <span class="o">=</span> <span class="s1">&#39;&lt;p&gt;Payment required.&lt;/p&gt;&#39;</span>
</pre></div>
</div>
<p>This is the minimal code you need for your own exception.  If you want to
add more logic to the errors you can override the
<code class="xref py py-meth docutils literal notranslate"><span class="pre">get_description()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">get_body()</span></code>,
<code class="xref py py-meth docutils literal notranslate"><span class="pre">get_headers()</span></code> and <a class="reference internal" href="#werkzeug.exceptions.HTTPException.get_response" title="werkzeug.exceptions.HTTPException.get_response"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_response()</span></code></a>
methods.  In any case you should have a look at the sourcecode of the
exceptions module.</p>
<p>You can override the default description in the constructor with the
<code class="docutils literal notranslate"><span class="pre">description</span></code> parameter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">raise</span> <span class="n">BadRequest</span><span class="p">(</span><span class="n">description</span><span class="o">=</span><span class="s1">&#39;Request failed because X was not present&#39;</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
  <span id="sidebar-top"></span>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  
    
            <p class="logo"><a href="../index.html">
              <img class="logo" src="../_static/werkzeug.png" alt="Logo"/>
            </a></p>
  

  <h3>Contents</h3>
  <ul>
<li><a class="reference internal" href="#">HTTP Exceptions</a><ul>
<li><a class="reference internal" href="#werkzeug-exceptions">werkzeug.exceptions</a><ul>
<li><a class="reference internal" href="#usage-example">Usage Example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#error-classes">Error Classes</a></li>
<li><a class="reference internal" href="#baseclass">Baseclass</a></li>
<li><a class="reference internal" href="#special-http-exceptions">Special HTTP Exceptions</a></li>
<li><a class="reference internal" href="#simple-aborting">Simple Aborting</a></li>
<li><a class="reference internal" href="#custom-errors">Custom Errors</a></li>
</ul>
</li>
</ul>
<h3>Navigation</h3>
<ul>
  <li><a href="../index.html">Overview</a>
    <ul>
          <li>Previous: <a href="../middleware/profiler/index.html" title="previous chapter">Application Profiler</a>
          <li>Next: <a href="../deployment/index.html" title="next chapter">Application Deployment</a>
    </ul>
  </li>
</ul>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="https://werkzeug.palletsprojects.com/en/1.0.x/search/" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  
    <div class="footer" role="contentinfo">
        &#169; Copyright 2007 Pallets.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.5.
    </div>
    <script>
      if (typeof READTHEDOCS_DATA !== 'undefined') {
        if (!READTHEDOCS_DATA.features) {
          READTHEDOCS_DATA.features = {};
        }
        READTHEDOCS_DATA.features.docsearch_disabled = true;
      }
    </script>

  </body>

<!-- Mirrored from werkzeug.palletsprojects.com/en/1.0.x/exceptions/ by HTTrack Website Copier/3.x [XR&CO'2014], Tue, 15 Sep 2020 06:37:09 GMT -->
</html>